/*
 * BigUtility.java
 *
 * Created on 1 March 2004, 11:20
 *
 * Copyright 2008 the Desert Labs Project (http://desertlabs.us)
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package us.desertlabs.number;

import java.math.BigDecimal;

/**
 * This utility class provides some methods that are useful for managing <CODE>BigDecimal</CODE>s
 * in a uniform way. It provides the ability to set a single scale value and
 * rounding mode, which <CODE>BigDecimal</CODE>s can then be normalized or
 * clipped to with a single method call.
 *
 * @author Brandon Franklin
 */
public final class BigUtility {

    /** The rounding mode used when reducing scale of <CODE>BigDecimal</CODE>s */
    private static int roundingMode = BigDecimal.ROUND_HALF_UP;

    /** The scale used to clip and normalize <CODE>BigDecimal</CODE>s */
    private static int scale = 0;

    /**
     * Given a <CODE>BigDecimal</CODE>, returns a <CODE>BigDecimal</CODE>
     * of equal value, but with its scale clipped to the scale that the <CODE>BigUtility</CODE>
     * has been configured to use. In other words, smaller scales will be left
     * untouched, but larger scales will be normalized. If the scale has to be
     * decreased and rounding is required, the rounding mode that the <CODE>BigUtility</CODE>
     * has been configured with will be used, or the "half up" mode will be used
     * by default.
     *
     * @param target the <CODE>BigDecimal</CODE> to clip
     * @return a <CODE>BigDecimal</CODE> equal to the value of the one
     *         supplied, but clipped to the scale configured in the <CODE>BigUtility</CODE>
     * @throws IllegalArgumentException if the supplied parameter is null
     */
    public static BigDecimal clipScale( final BigDecimal target ) {

        // Validate target
        if( target == null ) {
            throw new IllegalArgumentException( "Target parameter cannot be null." );
        }

        if( target.scale() <= BigUtility.scale ) {
            return target;
        }
        return normalizeScale( target );
    }

    /**
     * Given a <CODE>BigDecimal</CODE>, returns a <CODE>BigDecimal</CODE>
     * of equal value, but with its scale adjusted to the scale that the <CODE>BigUtility</CODE>
     * has been configured to use. If the scale has to be decreased and rounding
     * is required, the rounding mode that the <CODE>BigUtility</CODE> has
     * been configured with will be used, or the "half up" mode will be used by
     * default.
     *
     * @param target the <CODE>BigDecimal</CODE> to normalize
     * @return a <CODE>BigDecimal</CODE> equal to the value of the one
     *         supplied, but normalized to the scale configured in the <CODE>BigUtility</CODE>
     * @throws IllegalArgumentException if the supplied parameter is null
     */
    public static BigDecimal normalizeScale( final BigDecimal target ) {

        // Validate target
        if( target == null ) {
            throw new IllegalArgumentException( "Target parameter cannot be null." );
        }

        if( BigUtility.scale == target.scale() ) {
            return target;
        }
        return target.setScale( BigUtility.scale, BigUtility.roundingMode );
    }

    /**
     * Sets the rounding mode that the <CODE>BigUtility</CODE> will use when
     * decreasing the scale of <CODE>BigDecimal</CODE>s. The mode must be one
     * of the constant values defined in the <CODE>BigDecimal</CODE> class,
     * and defaults to <CODE>BigDecimal.ROUND_HALF_UP</CODE>.
     *
     * @param mode the rounding mode that the <CODE>BigUtility</CODE> will use
     *        to decrease the scale of <CODE>BigDecimal</CODE>s
     * @throws IllegalArgumentException if the supplied rounding mode is not
     *         supported by the <CODE>BigDecimal</CODE> class, or if <CODE>BigDecimal.ROUND_UNNECESSARY</CODE>
     *         is supplied
     */
    public static void setRoundingMode( final int mode ) {

        if( mode == BigDecimal.ROUND_UNNECESSARY ) {
            throw new IllegalArgumentException( "BigManager cannot be set to use the ROUND_UNNECESSARY mode." );
        }

        final BigDecimal dummy = BigDecimal.valueOf( 1, 1 );
        try {
            dummy.setScale( 0, mode );
        } catch( final IllegalArgumentException e ) {
            throw new IllegalArgumentException( "Supplied rounding mode is not valid." );
        }

        BigUtility.roundingMode = mode;
    }

    /**
     * Sets the scale that the <CODE>BigUtility</CODE> will use to clip and
     * normalize <CODE>BigDecimal</CODE>s. The scale defaults to zero.
     *
     * @param scale the scale that the <CODE>BigUtility</CODE> will use to
     *        clip and normalize <CODE>BigDecimal</CODE>s
     * @throws IllegalArgumentException if the supplied scale value is negative
     */
    public static void setScale( final int scale ) {

        if( scale < 0 ) {
            throw new IllegalArgumentException( "Scale value cannot be negative." );
        }

        BigUtility.scale = scale;
    }

    /**
     * Made private to prevent use.
     */
    private BigUtility() {
    }
}
